Créer un notebook avec Quarto: principes, fonctionnalités

Evolution des pratiques en SHS (FR)

Avant 2011 : des “black-boxes” méthodologiques

Logiciels payants, ruptures logicielles dans les chaines de traitements, stockage et partage des données et méthodes non optimisé, univers “clic-bouton”.

Evolution des pratiques en SHS (FR)

Evolution des pratiques en SHS (FR)

Depuis peu… : vers l’ouverture à de nouveaux langages ?

Usage de langages de développement variés en fonction des usages désirés (performence de certaines libs, interactivité, …) et des échanges interdisciplinaires (dataviz).

Comment passer d’un langage à l’autre dans des mêmes chaînes de traitement ?

Evolution des pratiques en SHS (FR)

La réplication en question

• Où sont stockées les données ?
• Sur quoi reposent ces protocoles méthodologiques ?
• Comment les documenter ?
• Comment les restituer / mettre à jour / adapter ?

Qui pour reprendre ces programmes ?

Qui pour comprendre ce code et ses intentions ?

Recherche reproductible

Programmation lettrée & notebooks

Notebooks : Principes fondamentaux

Le Notebook est une solution opérationnelle et adaptée pour arriver à ces fins

Source : Pecout, 2022

Les Notebooks du moment

Quarto : un des derniers nés des notebooks (2022)

Des sorties multiples

• Sites Web
• Présentations
• Rapports Interactifs
• Manuels
• Publications

Restituer des analyses reproductibles menées lors d’un projet.

Sortie (site Web) // Dépôt GitLab

Générer des présentations interactives (iframe, animations, slides interactifs) avec le format revealjs.

Exemple : Sortie (Présentation) // Dépôt GitHub // Code

Créer des raports interactifs combinant (éventuellement) plusieurs langages de programmation.

Sortie (Rapport interactif) // Dépôt GitHub // Code (Quarto)

Créer des manuels ou des sections pédagogiques collaboratifs au format Book.

Sortie (Book) // Dépôt GitHub

Soumettre des publications suivant les prérequis (adaptation template LaTeX) de plusieurs revues de référence (Public Library of Science, Elsevier, JSS, etc.)

Journal Articles (Quarto doc)

Squelette d’un notebook (Quarto)

Initier un document Quarto dans RStudio

RStudio propose plusieurs modèles pour initier aisément un notebook.

Initier un document Quarto dans RStudio

RStudio propose plusieurs modèles pour initier aisément un notebook.

Paramétrer son document grâce au YAML

---
title: "My document"
author: "Me"
format: html
---

Paramétrer son document grâce au YAML

---
title: "My pdf document"
author: "Me"
format: pdf
---

Paramétrer son document grâce au YAML

---
title: "My docx document"
author: "Me"
format: docx
---

Paramétrer son document grâce au YAML

---
title: "My presentation"
author: "Me"
format: revealjs / beamer / pptx
---

Paramétrer son document grâce au YAML

Paramétrer son document grâce au YAML

---
title: "OpenStreetMap data and associated routing engine to produce novel data on rural areas in Europe"
subtitle: "Review data and methods" 
author:
  - name: "Ronan Ysebaert, Marianne Guérois\n, Timothée Giraud, Nicolas Lambert, Matthieu Viry" 
    affiliation: UAR RIATE (CNRS,  Université Paris Cité) 
    affiliation-url: https://riate.cnrs.fr/
date: "2023-05-26"
description: "This review of the literature and data availability aims at providing an overview of possible solutions and limitations for creating accessibility indicators at European context. Whatever the solution retained, computing accessibility indicators requires relevant origins / destination pairs and routing engines for computing travel-time indicators. It is afterward possible to propose a large set of indicators derived from these measures. The first part of the document presents at European scale the policy context and the main initiatives developed so far for proposing harmonized indicators on accessibility. The second one reminds the main issues to be considered when calculating accessibility indicators (origin-destination pairs, routing engines, accessibility indicators computation). The third section makes an overview of existing databases and possibilities that could be considered in a European context for the selection of origins / destinations pairs. The fourth part highlights existing solutions for routing engines according to several transportation modes (road, cycle, transport-transit). Finally, the last section discusses on possibilities offered in term of indicator creation when the travel time matrix is calculated with a case-study on hospitals in France. This case-study could be extended in a cross-border context to test this framework within GRANULAR activities. At the end, this report aims at providing a general research framework on the activities that will be held on task 3.3.1 of the GRANULAR project: Crowd-sources data based on OpenStreetMap."
title-block-banner: "#27445C"
bibliography: bib.bib
format:
  html:
    theme: sandstone
    embed-resources: true
    smooth-scroll: true
    fontsize: 0.9em
    code-tools: true
    code-fold: true
    toc: true
    toc-title: Summary
    toc-depth: 2
    toc-location: left
    css: "styles.css"
    linkcolor: "#d52420"
---

Décrire simplement son cheminement en markdown

 ### Titre de niveau 3

*italics* and **bold**

superscript^2^ / subscript~2~

~~strikethrough~~

`verbatim code`

* unordered list
    + sub-item 1
    + sub-item 2
        - sub-sub-item 1

 [named hyperlinks](url)

Optimiser sa mise en page avec des classes préformatées

Ceci

::: columns

::: {.column width="50%"}
::: {.callout-tip}
## 5 types de callouts dispnibles
`note`, `warning`, `important`, `tip`, and `caution`.
:::
::: 

::: {.column width="50%"}
![](fig/callout.png)
:::

:::

Paramétrer ses blocs de code grâce aux chunks

Le code est à placer dans des chunks (tronçons), délimités par des triples backticks (Code > Insert Chunk dans R Studio).

Un même document Quarto peut combiner plusieurs langages de programmation :

```{julia}
radius = 10
using Markdown
Markdown.parse("""
The radius of the circle is $radius.
""")
```

```{python}
import matplotlib.pyplot as plt
plt.plot([1,2,3,4])
plt.show()
```

Paramétrer ses blocs de code grâce aux chunks

Le code est à placer dans des chunks (tronçons), délimités par des triples backticks (Code > Insert Chunk dans R Studio).

Un même document Quarto peut combiner plusieurs langages de programmation :

```{r}
library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess", se = FALSE)
```

Paramétrer ses blocs de code grâce aux chunks

Le code est à placer dans des chunks (tronçons), délimités par des triples backticks (Code > Insert Chunk dans R Studio).

Un même document Quarto peut combiner plusieurs langages de programmation :

```{ojs}
pdata = FileAttachment("palmer-penguins.csv").csv({typed: true})

Plot.plot({
  facet: {
    data: pdata,
    x: "sex",
    y: "species",
    marginRight: 80
  },
  marks: [
    Plot.frame(),
    Plot.rectY(pdata, 
      Plot.binX(
        {y: "count"}, 
        {x: "body_mass_g", thresholds: 20, fill: "species"}
      )
    ),
    Plot.tickX(pdata, 
      Plot.groupZ(
        {x: "median"}, 
        {x: "body_mass_g",
         z: d => d.sex + d.species,
         stroke: "#333",
         strokeWidth: 2
        }
      )
    )
  ]
})
```

Paramétrer ses blocs de code grâce aux chunks

En initiant le chunk par un hash pipe #| on peut paramétrer son exécution / affichage. Les arguments les plus usuels sont :

• label: toto : nommer le chunk
• eval: true/false : le bloc de code est joué ou non.
• echo: true/false : le bloc de code s’affiche ou non dans le document de sortie.
• cache: true/false : les résultats sont mis en cache et ne sont pas rejoués tant que le bloc de code reste inchangé.
• warning: true/false : affiche les messages d’alerte ou non.
• fig-height: 4 / fig-width: 6 : hauteur / largeur du plot de sortie, en pouces.
• dpi: 150: densité de pixels par pouce.

Paramétrer ses blocs de code grâce aux chunks

A noter / quelques conseils :

• Penser à générer (render) le document fréquemment pour veiller à la cohérence / bonne exécution de vos blocs de code.
• Pour vous comme pour les autres, évitez les blocs de code trop volumineux ou longs.
• Les paramètres des chunks peuvent aussi être spécifiés dans le YAML (setup chunk).
• L’usage de Knitr rend disponible encore davantage d’options

Paramétrer ses blocs de code grâce aux chunks / Exemples

```{r}
plot(1:10)
```

plot(1:10)

Paramétrer ses blocs de code grâce aux chunks / Exemples

```{r}
#| eval: false
#| echo: false
plot(1:10)
```

Paramétrer ses blocs de code grâce aux chunks / Exemples

```{r}
#| echo: false
plot(1:10)
```

Paramétrer ses blocs de code grâce aux chunks / Exemples

```{r}
#| fig-height: 6
#| fig-width: 4
#| fig-align: center
#| fig-cap: Un beau graphique ! 
#| code-fold: true
plot(1:10)
```

plot(1:10)

Ressources pour aller plus loin

Supports utiles

• Comprehensive guide to using Quarto
• Mock T., 2022, Get Started with Quarto, RStudio Conference : Intro to Quarto, Authoring Quarto, Code and Editors, Static Documents, Presentations, Websites & Books, Plot & Tables, Advanced Quarto.

Enjeux de la reproductibilité

• Brundson C., Comber A., 2020, Opening practice: supporting reproducibility and critical spatial data science, Journal of Geographical Systems 23.
• Desquilbet L., et al., 2019, Vers une recherche reproductible. Faire évoluer ses pratiques.
• Nüst D., Pebesma E., 2021, Practical Reproducibility in Geography and Geosciences, Annals of the Americal Association of Geographes, vol 111, 2021, Issue 5.

A vous de jouer !